
/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2017原作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证和
 *许可证下的限制。
 */

package org.springframework.scheduling.concurrent;

import java.util.concurrent.TimeUnit;

import org.springframework.lang.Nullable;
import org.springframework.util.Assert;

/**
 * JavaBean that describes a scheduled executor task, consisting of the
 * {@link Runnable} and a delay plus period. The period needs to be specified;
 * there is no point in a default for it.
 *
 * <p>The {@link java.util.concurrent.ScheduledExecutorService} does not offer
 * more sophisticated scheduling options such as cron expressions.
 * Consider using {@link ThreadPoolTaskScheduler} for such needs.
 *
 * <p>Note that the {@link java.util.concurrent.ScheduledExecutorService} mechanism
 * uses a {@link Runnable} instance that is shared between repeated executions,
 * in contrast to Quartz which creates a new Job instance for each execution.
 *
 * @author Juergen Hoeller
 * @since 2.0
 * @see java.util.concurrent.ScheduledExecutorService#scheduleWithFixedDelay(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit)
 * @see java.util.concurrent.ScheduledExecutorService#scheduleAtFixedRate(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit)
 */
/**
 *描述调度的执行器任务的JavaBean，由
 *｛@link Runnable｝和一个延迟加周期。需要指定期限；
 *它没有默认的意义。
 *
 *<p>｛@link java.util.concurrent.ScheduledExecutiorService｝不提供
 *更复杂的调度选项，如cron表达式。
 *考虑使用｛@link ThreadPoolTaskScheduler｝来满足这些需求。
 *
 *<p>请注意，｛@link java.util.concurrent.ScheduledExecutiorService｝机制
 *使用在重复执行之间共享的{@linkRunnable}实例，
 *与Quartz相反，Quartz为每次执行创建一个新的作业实例。
 *
 *@作者于尔根·霍勒
 *@自2.0起
 *@参见java.util.concurrent.ScheduledExecutiorService#scheduleWithFixedDelay（java.lang.Runnable，long，long、java.util.conconcurrent.TimeUnit）
 *@参见java.util.concurrent.ScheduledExecutiorService#scheduleAtFixedRate（java.lang.Runnable，long，long、java.util.conconcurrent.TimeUnit）
 */
public class ScheduledExecutorTask {

	@Nullable
	private Runnable runnable;

	private long delay = 0;

	private long period = -1;

	private TimeUnit timeUnit = TimeUnit.MILLISECONDS;

	private boolean fixedRate = false;


	/**
	 * Create a new ScheduledExecutorTask,
	 * to be populated via bean properties.
	 * @see #setDelay
	 * @see #setPeriod
	 * @see #setFixedRate
	 */
	/**
	 *创建一个新的ScheduledExecutionTask，
	 *通过bean属性填充。
	 *@参见#setDelay
	 *@参见#setPeriod
	 *@参见#setFixedRate
	 */
	public ScheduledExecutorTask() {
	}

	/**
	 * Create a new ScheduledExecutorTask, with default
	 * one-time execution without delay.
	 * @param executorTask the Runnable to schedule
	 */
	/**
	 *创建一个新的ScheduledExecutionTask，默认为
	 *立即一次性执行。
	 *@param executorTask要调度的可运行程序
	 */
	public ScheduledExecutorTask(Runnable executorTask) {
		this.runnable = executorTask;
	}

	/**
	 * Create a new ScheduledExecutorTask, with default
	 * one-time execution with the given delay.
	 * @param executorTask the Runnable to schedule
	 * @param delay the delay before starting the task for the first time (ms)
	 */
	/**
	 *创建一个新的ScheduledExecutionTask，默认为
	 *具有给定延迟的一次性执行。
	 *@param executorTask要调度的可运行程序
	 *@param delay第一次启动任务之前的延迟（ms）
	 */
	public ScheduledExecutorTask(Runnable executorTask, long delay) {
		this.runnable = executorTask;
		this.delay = delay;
	}

	/**
	 * Create a new ScheduledExecutorTask.
	 * @param executorTask the Runnable to schedule
	 * @param delay the delay before starting the task for the first time (ms)
	 * @param period the period between repeated task executions (ms)
	 * @param fixedRate whether to schedule as fixed-rate execution
	 */
	/**
	 *创建一个新的ScheduledExecutionTask。
	 *@param executorTask要调度的可运行程序
	 *@param delay第一次启动任务之前的延迟（ms）
	 *@param period重复执行任务之间的时间段（毫秒）
	 *@param fixedRate是否计划为固定速率执行
	 */
	public ScheduledExecutorTask(Runnable executorTask, long delay, long period, boolean fixedRate) {
		this.runnable = executorTask;
		this.delay = delay;
		this.period = period;
		this.fixedRate = fixedRate;
	}


	/**
	 * Set the Runnable to schedule as executor task.
	 */
	/**
	 *将Runnable设置为计划执行器任务。
	 */
	public void setRunnable(Runnable executorTask) {
		this.runnable = executorTask;
	}

	/**
	 * Return the Runnable to schedule as executor task.
	 */
	/**
	 *将Runnable返回到计划作为执行器任务。
	 */
	public Runnable getRunnable() {
		Assert.state(this.runnable != null, "No Runnable set");
		return this.runnable;
	}

	/**
	 * Set the delay before starting the task for the first time,
	 * in milliseconds. Default is 0, immediately starting the
	 * task after successful scheduling.
	 */
	/**
	 *在第一次启动任务之前设置延迟，
	 *以毫秒为单位。默认值为0，立即启动
	 *成功调度后的任务。
	 */
	public void setDelay(long delay) {
		this.delay = delay;
	}

	/**
	 * Return the delay before starting the job for the first time.
	 */
	/**
	 *返回首次启动作业之前的延迟。
	 */
	public long getDelay() {
		return this.delay;
	}

	/**
	 * Set the period between repeated task executions, in milliseconds.
	 * <p>Default is -1, leading to one-time execution. In case of a positive value,
	 * the task will be executed repeatedly, with the given interval in-between executions.
	 * <p>Note that the semantics of the period value vary between fixed-rate and
	 * fixed-delay execution.
	 * <p><b>Note:</b> A period of 0 (for example as fixed delay) is <i>not</i> supported,
	 * simply because {@code java.util.concurrent.ScheduledExecutorService} itself
	 * does not support it. Hence a value of 0 will be treated as one-time execution;
	 * however, that value should never be specified explicitly in the first place!
	 * @see #setFixedRate
	 * @see #isOneTimeTask()
	 * @see java.util.concurrent.ScheduledExecutorService#scheduleWithFixedDelay(Runnable, long, long, java.util.concurrent.TimeUnit)
	 */
	/**
	 *设置重复任务执行之间的时间段（以毫秒为单位）。
	 *<p>默认值为-1，导致一次性执行。在正值的情况下，
	 *任务将被重复执行，执行之间有给定的间隔。
	 *<p>请注意，周期值的语义在固定利率和
	 *固定延迟执行。
	 *<p><b>注意：</b>不支持0的周期（例如固定延迟）<i>，
	 *仅仅因为{@code java.util.concurrent.ScheduledExecutiorService}本身
	 *不支持。因此，值为0将被视为一次性执行；
	 *但是，该值不应该首先明确指定！
	 *@参见#setFixedRate
	 *@参见#isOneTimeTask（）
	 *@参见java.util.concurrent.ScheduledExecutiorService#scheduleWithFixedDelay（可运行，长，长，java.util.conconcurrent.TimeUnit）
	 */
	public void setPeriod(long period) {
		this.period = period;
	}

	/**
	 * Return the period between repeated task executions.
	 */
	/**
	 *返回重复执行任务之间的时间段。
	 */
	public long getPeriod() {
		return this.period;
	}

	/**
	 * Is this task only ever going to execute once?
	 * @return {@code true} if this task is only ever going to execute once
	 * @see #getPeriod()
	 */
	/**
	 *这个任务只执行一次吗？
	 *@return｛@code true｝如果此任务只执行一次
	 *@参见#getPeriod（）
	 */
	public boolean isOneTimeTask() {
		return (this.period <= 0);
	}

	/**
	 * Specify the time unit for the delay and period values.
	 * Default is milliseconds ({@code TimeUnit.MILLISECONDS}).
	 * @see java.util.concurrent.TimeUnit#MILLISECONDS
	 * @see java.util.concurrent.TimeUnit#SECONDS
	 */
	/**
	 *指定延迟和周期值的时间单位。
	 *默认值为毫秒（｛@code TimeUnit.milliseconds｝）。
	 *@请参阅java.util.concurrent.TimeUnit#百万秒
	 *@参见java.util.concurrent.TimeUnit#SECONDS
	 */
	public void setTimeUnit(@Nullable TimeUnit timeUnit) {
		this.timeUnit = (timeUnit != null ? timeUnit : TimeUnit.MILLISECONDS);
	}

	/**
	 * Return the time unit for the delay and period values.
	 */
	/**
	 *返回延迟和周期值的时间单位。
	 */
	public TimeUnit getTimeUnit() {
		return this.timeUnit;
	}

	/**
	 * Set whether to schedule as fixed-rate execution, rather than
	 * fixed-delay execution. Default is "false", that is, fixed delay.
	 * <p>See ScheduledExecutorService javadoc for details on those execution modes.
	 * @see java.util.concurrent.ScheduledExecutorService#scheduleWithFixedDelay(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit)
	 * @see java.util.concurrent.ScheduledExecutorService#scheduleAtFixedRate(java.lang.Runnable, long, long, java.util.concurrent.TimeUnit)
	 */
	/**
	 *设置是否计划为固定速率执行，而不是
	 *固定延迟执行。默认值为“false”，即固定延迟。
	 *<p>有关这些执行模式的详细信息，请参阅ScheduledExecutiorService javadoc。
	 *@参见java.util.concurrent.ScheduledExecutiorService#scheduleWithFixedDelay（java.lang.Runnable，long，long、java.util.conconcurrent.TimeUnit）
	 *@参见java.util.concurrent.ScheduledExecutiorService#scheduleAtFixedRate（java.lang.Runnable，long，long、java.util.conconcurrent.TimeUnit）
	 */
	public void setFixedRate(boolean fixedRate) {
		this.fixedRate = fixedRate;
	}

	/**
	 * Return whether to schedule as fixed-rate execution.
	 */
	/**
	 *返回是否安排为固定速率执行。
	 */
	public boolean isFixedRate() {
		return this.fixedRate;
	}

}
